evaporate

Evaporate

File Upload API for AWS S3

Evaporate is a javascript library for uploading files from a browser to AWS S3, using parallel S3's multipart uploads with MD5 checksum support and control over pausing / resuming the upload.

Major features include:

• Configurable number of parallel uploads for each part (maxConcurrentParts)
• Configurable MD5 Checksum calculations and handling for each uploaded part (computeContentMd5)
• AWS Signature Version 2 and 4 (awsSignatureVersion)
• S3 Transfer Acceleration (s3Acceleration)
• Robust recovery when uploading huge files. Only parts that have not been fully uploaded again. (s3FileCacheHoursAgo, allowS3ExistenceOptimization)
• Ability to pause and resume downloads at will
• Pluggable signing methods to support AWS Lambda, async functions and more.

New Features in v2.0:

• Parallel file uploads while respecting maxConcurrentParts.
• If Evaporate reuses an interrupted upload or avoids uploading a file that is already available on S3, the new callback nameChanged will be invoked with the previous object name at the earliest moment. This indicates that requested object name was not used.
• Pause, Resume, Cancel now can act on all in-progress file uploads
• Pluggable signing methods with customAuthMethod. AWS Lambda functions must be implemented through this option.
• Signing methods can respond to 401 and 403 response statuses and not trigger the automatic retry feature.
• The progress() and complete() callbacks now provide upload stats like transfer rate and time remaining.
• Reduced memory footprint when calculating MD5 digests.

New Features in v2.0.5:

• Support for Node.js FileSystem (fs) ReadbleStreams. This means you can use Electron to upload a file directly from the file system's native File picker and avoid the usual browser restrictions.

To migrate to v2.0, follow these instructions.

Installation

Evaporate is published as a Node module:

$ npm install evaporate

Otherwise, include it in your HTML:

<script language="javascript" type="text/javascript" src="../evaporate.js"></script>

Example

require('crypto');

var config = {
     signerUrl: <SIGNER_URL>,
     aws_key: <AWS_KEY>,
     bucket: <AWS_BUCKET>,
     cloudfront: true,
     computeContentMd5: true,
     cryptoMd5Method: function (data) { return crypto.createHash('md5').update(data).digest('base64'); }
};

return Evaporate.create(config)
    .then(function (evaporate) {

      var file = new File([""], "file_object_to_upload"),
          addConfig = {
            name: file.name,
            file: file,
            progress: function (progressValue) { console.log('Progress', progressValue); },
            complete: function (_xhr, awsKey) { console.log('Complete!'); },
          },
          overrides = {
            bucket: AWS_BUCKET // Shows that the bucket can be changed per
          };
      evaporate.add(addConfig, overrides)
          .then(function (awsObjectKey) {
                console.log('File successfully uploaded to:', awsObjectKey);
              },
              function (reason) {
                console.log('File did not upload sucessfully:', reason);
              });
    });

See more examples on wiki.

API documentation

• #create()
• #add()
• #cancel()
• #pause()
• #resume()
• #supported

Check out Browser Compatibility and Important Usage Notes for usage details.

Authors

• Bobby Wallace (bikeath1337)
• Tom Saffell (tomsaffell)

License

EvaporateJS is licensed under the BSD 3-Clause License http://opensource.org/licenses/BSD-3-Clause